Skip to content

feat: add agent-friendly migration CLI flags (--json, --dry-run, --from-stdin)#15921

Open
MarkKropf wants to merge 3 commits intopayloadcms:mainfrom
MarkKropf:feat/agent-friendly-migrations
Open

feat: add agent-friendly migration CLI flags (--json, --dry-run, --from-stdin)#15921
MarkKropf wants to merge 3 commits intopayloadcms:mainfrom
MarkKropf:feat/agent-friendly-migrations

Conversation

@MarkKropf
Copy link

Summary

  • Add --json, --dry-run, and --from-stdin flags to migrate:create and migrate CLI commands for non-interactive use by AI agents and CI pipelines
  • Return structured MigrationCreateResult and MigrateResult from all database adapter createMigration and migrate methods (replaces void returns and process.exit calls)
  • Add meaningful exit codes: 0 = success, 1 = error, 2 = no schema changes (with --skip-empty)
  • Add jsonReporter utility for stderr logger redirect and JSON stdout output
  • Update MongoDB, Drizzle, and base adapters for parity
  • Document new flags and agent workflow examples in migration docs

Test plan

  • 8 new integration tests covering all flag combinations (test/database/migrations-cli.int.spec.ts)
  • 3 existing migration CLI tests pass without regression
  • pnpm run build:core — 45/45 tasks, 0 type errors
  • pnpm run test:int:postgres migrations-cli — verify --skipEmpty exit code 2 test on Drizzle
  • Manual: pnpm run dev fields, then npx payload migrate:create --dry-run --json --skip-empty

MarkKropf and others added 3 commits March 11, 2026 16:09
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Addresses review feedback:
- Fix logger stderr redirect (reassign after init, not via InitOptions)
- Add MongoDB --from-stdin support
- Add missing tests (mutually exclusive flags, exit codes, JSON output)
- Remove duplicate dry-run guard
- Fix markdown fence in docs
- Remove json from adapter args (CLI handles serialization)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…om-stdin)

Add composable CLI flags and meaningful exit codes to migrate:create and
migrate commands so AI agents and CI pipelines can reliably detect, create,
and run migrations without interactive prompts.

- Add MigrationCreateResult and MigrateResult types
- Return structured results from createMigration and migrate adapters
- Add --json flag to output structured JSON to stdout (logger to stderr)
- Add --dry-run flag to preview changes without writing files
- Add --from-stdin flag to accept migration SQL via piped JSON
- Add exit code 2 for "no changes" on migrate:create
- Replace process.exit calls with thrown errors in adapters
- Add forceAcceptWarning support to skip dev-mode prompts
- Add 8 new integration tests for all flag combinations
- Document new flags and agent workflow examples
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant